Playwright 1.61 实战（含组件测试）

# 1. 初始化（交互式选择 TS/JS、目录、是否安装 GitHub Actions）
npm init playwright@latest

# 2. 显式安装浏览器二进制（CI 中需单独执行）
npx playwright install

# 3. 仅安装指定浏览器，节省 CI 时间
npx playwright install chromium firefox

# 4. 安装系统依赖（Linux 容器中必需）
npx playwright install-deps

my-e2e/
├── playwright.config.ts     # 全局配置
├── tests/
│   ├── example.spec.ts      # 测试用例
│   └── fixtures.ts          # 自定义 fixture
├── tests-examples/          # 示例代码
└── playwright-report/       # 测试报告（gitignore）

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  // 1. 测试目录与匹配模式
  testDir: './tests',
  fullyParallel: true,          // 文件级并行
  forbidOnly: !!process.env.CI, // CI 中禁止 test.only
  retries: process.env.CI ? 2 : 0, // CI 重试 2 次，本地不重试
  workers: process.env.CI ? 4 : undefined, // CI 限制并发数

  // 2. 报告器
  reporter: [
    ['html', { open: 'never' }],          // 本地 HTML 报告
    ['list'],                              // 控制台列表
    ['junit', { outputFile: 'junit.xml' }], // CI 解析用
  ],

  // 3. 全局行为
  use: {
    baseURL: 'https://demo.example.com',  // 相对路径的基准地址
    trace: 'on-first-retry',              // 首次重试时采集 Trace
    screenshot: 'only-on-failure',        // 失败时截图
    video: 'retain-on-failure',           // 1.61 新模式：失败保留视频
    actionTimeout: 10_000,                // 单个动作超时 10s
    navigationTimeout: 30_000,            // 导航超时 30s
  },

  // 4. 多浏览器项目配置
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox',  use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit',   use: { ...devices['Desktop Safari'] } },
    { name: 'mobile',   use: { ...devices['Pixel 7'] } },
  ],
});

import { test, expect } from '@playwright/test';

test('登录后跳转主页', async ({ page, context }) => {
  // page 由 fixture 自动创建，每个 test 独立 BrowserContext
  await page.goto('/login');

  // 同时打开新页面验证多角色（同一 context 共享会话）
  const page2 = await context.newPage();

  // 关闭 context 即销毁所有会话状态
  await context.close();
});

import { test, expect } from '@playwright/test';

test('Locator 最佳实践', async ({ page }) => {
  // 优先级：getByRole > getByLabel > getByText > css > xpath
  await page.goto('/register');

  // 1. 语义化定位（推荐）
  const emailInput = page.getByRole('textbox', { name: '邮箱' });
  const submitBtn  = page.getByRole('button', { name: '注册' });

  // 2. 链式过滤：先定位卡片再定位按钮
  const cardBtn = page.locator('.product-card').filter({ hasText: 'Pro' })
                    .getByRole('button', { name: '购买' });

  // 3. 等价断言：自动重试至超时
  await expect(emailInput).toBeVisible();
  await expect(cardBtn).toHaveCount(1);

  // 4. 交互：内置 auto-wait，无需手动等待
  await emailInput.fill('user@example.com');
  await submitBtn.click();
});

import { test, expect } from '@playwright/test';

test('异步列表加载', async ({ page }) => {
  await page.goto('/orders');

  // 错误：直接读取，可能拿不到值
  // const text = await page.textContent('.count');

  // 正确：web-first 断言自动重试
  await expect(page.locator('.count')).toHaveText('128', { timeout: 10_000 });

  // 常用断言：toBeVisible / toBeEnabled / toHaveText / toHaveCount
  // toContainText / toHaveAttribute / toHaveURL / toHaveTitle
  await expect(page).toHaveURL(/orders\?status=/);
  await expect(page.getByTestId('toast')).toContainText('成功');
});

import { test, expect } from '@playwright/test';

test.describe('订单管理', () => {
  test.beforeAll(async () => {
    // 整个 describe 内仅执行一次，适合启动 Mock 服务
  });

  test.beforeEach(async ({ page }) => {
    // 每个用例执行前自动登录，复用 storageState 更高效
    await page.goto('/login');
    await page.getByLabel('用户名').fill('admin');
    await page.getByLabel('密码').fill('pwd');
    await page.getByRole('button', { name: '登录' }).click();
    await expect(page).toHaveURL('/dashboard');
  });

  test('创建订单', async ({ page }) => {
    await page.getByRole('link', { name: '新建订单' }).click();
    await page.getByLabel('商品').fill('SKU-001');
    await page.getByRole('button', { name: '提交' }).click();
    await expect(page.getByTestId('order-id')).toBeVisible();
  });

  test.afterEach(async ({ page }, testInfo) => {
    // 失败时额外截图，testInfo 携带用例元信息
    if (testInfo.status !== testInfo.expectedStatus) {
      await page.screenshot({ path: `fail-${testInfo.title}.png` });
    }
  });
});

import { test as base, expect } from '@playwright/test';
import { ApiClient } from '../src/api-client';

// 1. 扩展 fixture 类型
type Fixtures = {
  authedPage: import('@playwright/test').Page;
  apiClient: ApiClient;
};

export const test = base.extend<Fixtures>({
  // 2. 自动登录的 Page
  authedPage: async ({ browser }, use) => {
    const context = await browser.newContext({
      storageState: 'tests/.auth/admin.json', // 复用登录态文件
    });
    const page = await context.newPage();
    await use(page);
    await context.close();
  },

  // 3. 依赖 authedPage 的 API 客户端
  apiClient: async ({ authedPage }, use) => {
    const client = new ApiClient(authedPage);
    await use(client);
  },
});

export { expect };

// 使用：参数即依赖，Playwright 自动注入
test('查询订单列表', async ({ apiClient, authedPage }) => {
  const orders = await apiClient.listOrders();
  expect(orders.length).toBeGreaterThan(0);
});

const cases = [
  { user: 'admin',    expectRole: '管理员' },
  { user: 'operator', expectRole: '运营' },
  { user: 'viewer',   expectRole: '访客' },
];

for (const { user, expectRole } of cases) {
  test(`用户 ${user} 看到角色 ${expectRole}`, async ({ page }) => {
    await page.goto(`/profile?u=${user}`);
    await expect(page.getByTestId('role')).toHaveText(expectRole);
  });
}

# 1. 触发 Trace 采集（配置中已设 trace: 'on-first-retry'）
npx playwright test --trace=on

# 2. 打开 Trace（自动加载最近一次失败）
npx playwright show-trace trace.zip

# 3. 直接查看 HTML 报告中的 Trace 链接
npx playwright show-report

# React 项目
npm install -D @playwright/experimental-ct-react

# Vue / Svelte 项目
npm install -D @playwright/experimental-ct-vue
npm install -D @playwright/experimental-ct-svelte

import { defineConfig, devices } from '@playwright/experimental-ct-react';

export default defineConfig({
  testDir: './src/components/__tests__',
  use: {
    ctViteConfigPath: 'vite.config.ts', // 复用项目 Vite 配置
    trace: 'retain-on-failure',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
  ],
});

import { test, expect } from '@playwright/experimental-ct-react';
import { Counter } from '../Counter';

test('计数器交互', async ({ mount }) => {
  // 1. 挂载组件到隔离页面，返回组件根 Locator
  const component = await mount(<Counter initial={5} />);

  // 2. 断言初始状态
  await expect(component.getByText('当前：5')).toBeVisible();

  // 3. 触发交互：与 E2E 完全一致的 API
  await component.getByRole('button', { name: '加一' }).click();
  await component.getByRole('button', { name: '加一' }).click();

  // 4. web-first 断言验证结果
  await expect(component.getByText('当前：7')).toBeVisible();
});

test('透传 props 与事件', async ({ mount }) => {
  let lastValue = 0;
  const component = await mount(
    <Counter initial={0} onChange={(v) => (lastValue = v)} />
  );
  await component.getByRole('button').click();
  expect(lastValue).toBe(1);
});

// playwright.config.ts
use: {
  video: 'retain-on-first-failure', // 1.61 新增
}

# 启动 UI Mode，自动监听文件变化并重跑
npx playwright test --ui

# 配合指定项目
npx playwright test --ui --project=chromium

# 1. 基础录制
npx playwright codegen https://demo.example.com

# 2. 保存登录态后再录制（避免重复登录）
npx playwright codegen --save-storage=auth.json https://demo.example.com

# 3. 加载已有登录态继续录制
npx playwright codegen --load-storage=auth.json https://demo.example.com

# 4. 模拟设备
npx playwright codegen --device='iPhone 15' https://demo.example.com

# .github/workflows/e2e.yml
name: E2E Tests
on:
  pull_request:
  push:
    branches: [main]

jobs:
  test:
    timeout-minutes: 30
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shardIndex: [1, 2, 3, 4]   # 4 路分片并行
        shardTotal: [4]
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - run: npm ci

      # 官方 Action：自动缓存浏览器二进制
      - name: Install Playwright Browsers
        uses: microsoft/playwright-github-action@v1

      - name: Run tests (sharded)
        run: npx playwright test --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}

      - name: Upload HTML report
        if: ${{ !cancelled() }}
        uses: actions/upload-artifact@v4
        with:
          name: playwright-report-${{ matrix.shardIndex }}
          path: playwright-report/
          retention-days: 14

# Dockerfile.ci
FROM mcr.microsoft.com/playwright:v1.61.0-jammy
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
CMD ["npx", "playwright", "test"]

# 4 路分片（每个 Job 跑 1/4 用例）
npx playwright test --shard=1/4
npx playwright test --shard=2/4
npx playwright test --shard=3/4
npx playwright test --shard=4/4

# 合并分片报告（1.61 支持跨 shard 合并）
npx playwright merge-reports --reporter html ./blob-report